FastAPI API Doc

はじめに

APIドキュメントはSwaggerかRedocどちらのタイプでも閲覧可能になってる。

このAPIドキュメントを生成する際の、コードでAPI仕様を表現する方法をTipsとしてまとめておく。

基本的なポイントをコードと一緒に説明

code: sample.py

from fastapi import FastAPI

from pydantic import BaseModel, Field

app = FastAPI()

class ResponseModel(BaseModel):

id: int = Field(description='reponse ID') # レスポンス属性値の説明

name: str = Field(default='hoge', description='response Name')

@app.get( # APIのmethodとして表記

'/hoge', # API pathとして表記

description='This is hoge page.', # APIの詳細説明として表記

response_description='response description', # レスポンスのタイトルとして表記

response_model=ResponseModel,

status_code=200) # 正常レスポンスのステータスコード表記

def hoge():

return ResponseModel(id=1, name='aaaaa')

その他アドバンスドなポイント

1. APIドキュメントでは、リクエストパラメータの違いを把握してくれる

path, query, bodyの違いをしっかり把握し、APIドキュメントにどのパラメータかを表記してくれる。

2. APIの説明（description）は、docstringでも記載可能。というかそっちの方がより具体的に記載できる

3. エラーレスポンスを表記するには、responsesとBaseModelを使うとよろしい

code: sampel.py

class ErrorDetail(BaseModel):

msg: str

code: str

class ErrorResponse(BaseModel):

@app.get(

'/hoge',

...,

responses={

400: {"model": ErrorResponse},

404: {"model": ErrorResponse}

)

)

def hoge():

...

4. OpenAPIの"examples"にデータを自動出力したいならスキーマに記載しよう

responseスキーマに記載すると反映される。

参考